COMMENT ⊗   VALID 00002 PAGES
C REC  PAGE   DESCRIPTION
C00001 00001
C00002 00002	P2SYS documentation for wizards:
C00023 ENDMK
C⊗;
P2SYS documentation for wizards:

1.  There are three pages of common data used by both P1 and P2.  If P2
is up, these pages are the first three physical P2 pages, which are
pages 14000-14002 in P1 physical address space.  If P2 memory is down
(not to be confused with up but not running), three random pages in P1
memory (above FSLIMIT) are used.  In either case the three pages are
accessed through three constant exec virtual page numbers assembled into
the system.  The first of these virtual pages is called P2MEXP and the
P1 virtual address of the first word is P2VORG.  Cells in this area are
given the same symbolic name in the P1 and P2 systems, but the symbols
have different values, so for example the symbol P1NUM, which refers to
P2 physical location 100, has value 100 in the P2 system and value
P2VORG+100 in the P1 system.

2.  The following cells control the running of P2:
	P1NUM	set to -1 by P1 when it has initialized to the point
		where it wants P2 to run.  If P1NUM becomes zero, P2
		goes to P2INI and waits there for it to be nonzero.
		Reloading P2 does NOT affect this cell (P2 memory is
		loaded by P2LOAD starting from location 200), so if
		P2 is reloaded while the P1 system is up, P2INI need
		not wait for this flag.

	P2NUM	set to -1 by P2 when it gets to P2INI.  Reloading
		P2 zeros the cell.  If the cell becomes zero while
		P2SYS is running, P2 shuts down and loops at its
		location 101 (called P2LOOP).  The P2LOAD program
		zeros P2NUM before loading P2SYS, then puts a jump
		to 204 into 101 to restart P2.

	DETFLG	This cell is set to -1 by P2 when it is ready to
		run devices for P1, i.e. at the end of P2INI.  P1
		checks this flag to see whether to allow users to
		run the P2 devices.  It is zeroed when P2 is reloaded.

	NOP2	This cell is NOT in the shared data area, but only in
		P1.  It is -1 if P2 memory is down, so attempts to
		reload P2 will fail.  It is set in SYSINI when P1 is
		reloaded; it'll be -1 if there is a NXM in P2 memory
		at CORINI, or 0 if P1 can restart P2 (P1 clears P1NUM
		and P2NUM, then checks for P2NUM being set).  If neither
		condition holds, the operator is asked how to set the flag.

	HNGP2F	This cell is set to -1 by anyone who zeros DETFLG.  P1
		clock level AOSNs it to test for P2 having just gone
		down, and if so, it causes a hung timeout for any job
		with a P2 device INITed.

3.  Data common to both processors are kept in the file P2COMM.  Data for
P1 only remain in ALLDAT, and there is a P2DATA file for P2-only data.
LOA@SYS still loads the P1 system, and LOA@P2 the P2 system.  Both
systems contain HEAD and OUTER, so P2 can use P1's parameter definitions
and feature test switches.  HEAD contains version number information for
both systems.  It is possible to modify one system and not the other, as
long as P2COMM is not modified.  If P2COMM is changed, so the addresses
of variables change, both systems must be recompiled.  As a partial check
of system compatibility, P1 clock level occasionally checks a table in
P2COMM of addresses of a few P2COMM cells against the addresses of those
cells known by P1; if the addresses don't agree, P1 will try to reload
P2 (but only once) and will type a message on the CTY.  Nevertheless,
it is possible to change P2COMM in a way which will not be caught by
this check but will still prevent P2 from working (or maybe even crash
P1) so make sure to keep the systems compatible.

4.  There is no code which is run by both processors; things like PWAIT
which both processors need are duplicated in P2SER.  Therefore, PID and
SKIPP1/SKIPP2 are obsolete.  Not all references to them have been removed
from the P1 system yet, though, and P1 still keeps 0 in PID.

5.  P2SYS includes DDT and symbols.  You can set breakpoints, etc., as
on P1.  To get to DDT (like the EDDT command on P1), type control-X on
the P2 console TTY.

6.  Since P2 doesn't run spacewar, and has its own storage management
system, P1 no longer has to PSYNC/XSYNC in the spacewar scheduler or
in the free storage routines.  There are still PSYNCs in the device
servers for P2 devices, however.  To prevent a hung P2 from hanging
P1 indefinitely, the P1 version of PWAIT will not wait forever.  It
counts down from an initial value which is normally 0,,-1 and is found
in the (shared) cell WAITCT.  If you are debugging P2 and want to put
a breakpoint in P2 code which runs PSYNCed, you should set WAITCT to
-1 first, which will make P1 wait essentially forever on a PSYNC.
If MAINTM or TTYLOK is set, you get this for free.

7.  P2SYS does not have a free storage system like that of WAITS.  P2 has
128K available to it; all of the core not taken up by P2SYS itself is
available for the use of the XGP.  In character mode, that space is
assigned to the font compiler: when XGPSER creates a font compiler job,
it puts the job number in the cell XFCJN (in P2COMM).  The P1 CORE routines
recognize any core request for this job as a special case (handled at
COREFC in CORE).  Any nonzero request causes the FC job to get the entire
P2 memory, minus what P2SYS uses, in its map; a zero request clears the
map.  When the job has core, it has JLOCK set, but its core is not included
in the normal core accounting (HIFREE, LOKTOT, etc) since it was already
allocated to P2 anyway and is never available to user jobs other than the
FC.  If for some reason (such as a P2 reload in the middle of running the
XGP) XGPSER tries to create a new FC while CORE still knows about an old
one (it keeps its own copy of XFCJN in XFCJN1), CORE will stop the old
FC job and clear its map.  If the XGP is used in dump mode, the space above
P2SYS is used as a ring of buffers.  P1 copies data from the user program
into these buffers as needed; P2 requests another buffer by interrupting
P1 with the P1/P2 interface device.  P1 interrupts P2 when done copying.

8.  The memory used by P2 is also in P1's physical memory space, at
addresses 14 000 000 through 14 377 777.  To make this work, P2 has
been modified to set the 14 000 000 bits on all memory requests.  The
modification is actually in the BBN pager, not the KA itself, and is
controlled by a switch on the left side of the pager inside its door.
The switch must be on (up) to run the FTP2SP system and must be off
(down) to run the old system.  It is intended that the KA run in
Suppes memory, but before that can be done Suppes must be modified to
read 22-bit addresses.  Until that modification is made, the Suppes
memory cannot be used in an FTP2SP system; the configuration used is
the MG10 at addresses 0 to 777 777, and the ARM10M at 5 000 000 through
14 777 777.  Therefore there is a hole in physical address space.
(In the eventual configuration, the ARM will be 1 000 000 through 10 777 777
and there will still be a hole, but in a different place.)  The assembly
switch FTP2SUP should be set on (-1) when Suppes is available for P2.
It is also possible to run the FTP2SP system for debugging even if the
ARM is down, by using half the MG as 0 through 377 777, Suppes as 400 000
through 777 777, and the other half of the MG as 14 000 000 to 14 377 777.
This requires a modification to CORINI which is not an assembly switch
but is REPEAT 0ed out normally.  Note that because of the split MG, this
configuration requires I X2.  Also, because this leaves only 256K for
the P1 system and users (and that isn't enough to compile or load the P1
system), it might be advantageous to set P2SIZE (in OUTER) to only 64K
instead of 128K if the ARM-10M is to be down for a while.

9.  Reloading P1 normally doesn't reload P2 -- it just restarts it.  Here
is what happens in various situations:

    (A) Reloading the KL.  Since ONCE runs unmapped it can't do anything
    about P2.  Instead, the relevant code from ONCE is subroutinized and
    called from SYSINI after the map is set up.  This code clears P1NUM
    and P2NUM.  P1NUM is a flag to P2 to reinitialize (if it's running).
    After clearing these two cells, P1 waits a while for P2NUM to be set
    by P2, after which P2 will wait forever for P1NUM to be set by P1.  If
    P2 fails set to P2NUM within a few seconds, P1 asks the operator to
    restart P2 at 204.  If P2NUM comes on within about 20 seconds, P1
    continues starting up the system.  If the operator types either U
    (for Up) or D (for Down) within 20 seconds, then P1 takes that as the
    state of P2 memory and continues starting up the system.  If neither
    P2NUM gets set nor anything is typed for 20 seconds, P1 assumes U (P2
    memory up) and starts up the system; in this case ONCEP2 (executed by
    P1) assumes that the operator tried to start P2 and it didn't work,
    e.g., P2 core is clobbered, so the FIREUP mechanism is used to cause
    P2LOAD to run as a phantom to try to get P2 going.  If the operator
    says D, then P1 sets a flag (NOP2) which will prevent a user from
    later trying to reload P2 manually.  Also, any NXM found in P2 memory
    during CORINI will also set NOP2 to prevent trying to load P2.  A
    DEVCMR bit (DEVP2) tells ASSASG to pretend all P2 devices are detached
    if P2NUM is zero.  If P2 is under control, it should get to P2INI and
    type out its startup message.

    (B) Reloading the KA.  First of all, the P2UUO to make P2 memory be
    the user's upper segment will fail if NOP2 is set, so you can't do it
    if the operator said not to.  Otherwise, what P2LOAD does is first
    zero P2NUM.  (P2NUM is location 210, right after the dispatch table,
    in P2 memory.)  This tells P2 clock level to set location 101 (below
    200, so not affected by the disk operation which reloads its memory)
    to a JRST 101, then turn off the PIs and jump there.  Then the user
    program does the actual reload, then it sets 101 to be JRST 204.  This
    starts up P2INI.

    (C) P2INI always loops until P1NUM is set, to prevent P2 restarting
    before P1 is ready on a reload.  P1 does a SETOM P1NUM (in ONCEP2)
    when it's ready for P2.  P1NUM is location 100 in P2 memory, so
    reloading P2 doesn't turn it off.

    (D) The P2LOAD monitor command, accepted only from the CTY, runs the
    program P2LOAD.DMP[1,2] with ACW, which is required to get at P2's
    core from a P1 user program.  The program will not work if NOP2 is
    set, meaning that P2's memory is down.  The program FIXP2.DMP[SS,SYS]
    can be used by someone with the DEV privilege to change the setting of
    NOP2.  (There's more to it than that; changing NOP2 also has to
    reallocate the space for the P2COMM cells into or out of P2 memory.)
    Note that the system will crash if P2's memory is declared up when
    it's really down.  The FIXP2 program can also be used to find out the
    state of P2 and its memory.

10. I/O programming: DDBs for all devices are in P1-only memory, so
that the DDB chain can't be broken by P2 problems.  For the P2
devices, those cells which must be used by P2 have been moved out of
the DDB into P2.  These are all device-specific ones, except for
DEVIOS.  So that general purpose routines can always find IOS without
having to know whether a device is on P2 or P1, a new DDB word called
DEVSPT (Status PoinTer, word -2 of the DDB) which points to DEVIOS for
P1 devices and to a word in P2COMM for P2 devices.  General routines
which must work for any device should get IOS by MOVE IOS,@DEVSPT(DDB)
rather than directly from DEVIOS.  (There is a DEVIOS word in the P2
device DDBs so the addresses are right, but the word is not used.)
There is a DEVP2 bit in the left half of DEVCMR(DDB) which is on for
P2 devices.  Another bit, DEVP2H, is set on if P2 crashes (DETFLG
becomes zero) and is used by DEVCHK to give an immediate hung timeout
error message, whether or not the device is active.  (In particular,
this message may appear even if the job using the device is stopped!)

11. In P1 EXEC DDT, the command $$¬ (altmode altmode control-E) will put
P2 into its DDT and will send characters typed at the P1 CTY to P2 EDDT.
This is not super useful from the actual P1 CTY but can be used when
dialed into the KLINIC line from home.  You can set P2 breakpoints, etc.,
and continue P2SYS by typing CPOPJ$G.  When you want to get back to P1
EDDT (which you have to do before you can continue WAITS) first get P2
going (i.e. CPOPJ it) then type just ¬ (control-E) (with no altmode!).
That will type P1 EDDT and you're back.  Also, with WAITS running, the
user program UP2DDT[SS,SYS] (requires ACW) will put P2 into DDT and let
you type at it without interfering with P1 timesharing.  Type αβE to
UP2DDT when you have continued P2 (by CPOPJ$G) and are through using
UP2DDT; the αβE exits after re-enabling P1 hung timeouts for P2 devices,
in case you disabled them when you started up UP2DDT (when UP2DDT starts,
it asks you if you want to disable hung timeouts for P2 devices, and you
probably do since P2 will be in DDT).